NexusPi Git Node
>RRC Bot
An extensible service bot framework for Reticulum Relay Chat.
The goal is the same practical shape that made Eggdrop useful on IRC: a small
long-running bot core, persistent identity, room membership, command dispatch,
operator-friendly configuration, and scripts that can add behavior without
forking the bot.
Install
T282828
python -m venv .venv
Tffa657source .venv/bin/activate
pip install -e .Tff7b72[devTff7b72]
Configure
On first start, the bot checks for T383838~/.rrc-bot/bot.json. If it does not
exist, the bot creates that file from T383838bot.example.json, logs that you should
edit it, and exits.
Default config path:
T383838~/.rrc-bot/bot.json
The generated config looks like this:
T282828
Tb4b4b4{
Tff7b72"nickname"Tb4b4b4: Ta5d6ff"RRCBot"Tb4b4b4,
Tff7b72"identity_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/identity"Tb4b4b4,
Tff7b72"hubs_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/hubs.json"Tb4b4b4,
Tff7b72"roles_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/roles.json"Tb4b4b4,
Tff7b72"scripts_path"Tb4b4b4: Ta5d6ff"scripts"Tb4b4b4,
Tff7b72"command_prefixes"Tb4b4b4: Tb4b4b4[Ta5d6ff"!"Tb4b4b4],
Tff7b72"connect_timeout_seconds"Tb4b4b4: T79c0ff30Tb4b4b4,
Tff7b72"reconnect_delay_seconds"Tb4b4b4: T79c0ff10Tb4b4b4,
Tff7b72"reconnect_alert_threshold"Tb4b4b4: T79c0ff5Tb4b4b4,
Tff7b72"reconnect_alert_window_seconds"Tb4b4b4: T79c0ff300Tb4b4b4,
Tff7b72"ping_interval_seconds"Tb4b4b4: T79c0ff60Tb4b4b4,
Tff7b72"lxmf_storage_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/lxmf"Tb4b4b4,
Tff7b72"lxmf_announce_interval_seconds"Tb4b4b4: T79c0ff1800Tb4b4b4,
Tff7b72"room_notice_cooldown_seconds"Tb4b4b4: T79c0ff30Tb4b4b4,
Tff7b72"log_level"Tb4b4b4: Ta5d6ff"INFO"Tb4b4b4,
Tff7b72"log_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/rrc-bot.log"Tb4b4b4,
Tff7b72"log_max_bytes"Tb4b4b4: T79c0ff1048576Tb4b4b4,
Tff7b72"log_backup_count"Tb4b4b4: T79c0ff5Tb4b4b4,
Tff7b72"healthcheck_path"Tb4b4b4: Ta5d6ff"~/.rrc-bot/health.json"Tb4b4b4,
Tff7b72"healthcheck_interval_seconds"Tb4b4b4: T79c0ff15Tb4b4b4,
Tff7b72"command_denial_alert_threshold"Tb4b4b4: T79c0ff20Tb4b4b4,
Tff7b72"command_denial_alert_window_seconds"Tb4b4b4: T79c0ff300Tb4b4b4,
Tff7b72"operator_identities"Tb4b4b4: Tb4b4b4[Ta5d6ff"aabbcc..."Tb4b4b4],
Tff7b72"admin_identities"Tb4b4b4: Tb4b4b4[Ta5d6ff"ddeeff..."Tb4b4b4]
Tb4b4b4}
T383838operator_identities and T383838admin_identities are hex-encoded RRC identity
hashes used for command authorization (for example, T383838!status). Admins inherit
operator access.
T383838roles_path stores persisted operator/admin identities managed through the
T383838!role command.
T383838hubs_path stores the persisted hub registry, active hub selection, and room
membership list for each hub. Manage hubs at runtime with T383838!hub list,
T383838!hub add <hub>, T383838!hub del <hub>, and T383838!hub use <hub>. Use T383838!room add <room>
and T383838!room del <room> to manage room membership for the currently active hub.
The service can maintain multiple concurrent hub connections per bot instance,
with a separate persisted room list per hub.
Example hub workflow with friendly names:
T282828
!hub add 00112233445566778899aabbccddeeff PrimaryHub
!hub add ffeeddccbbaa99887766554433221100 LabHub
!hub connect PrimaryHub
!hub list
!hub use LabHub
!hub connect LabHub
!hub disconnect PrimaryHub
!hub set LabHub autoconnect off
!hub set LabHub auto-reconnect on
!hub info LabHub
T383838!hub use, T383838!hub connect, T383838!hub disconnect, T383838!hub info, and T383838!hub del
accept either the hub hash or the friendly name configured with
T383838!hub add ... [name].
T383838!hub list also shows the discovered HELLO name advertised by the hub when
available.
T383838autoconnect and T383838auto_reconnect are configured per hub inside T383838hubs.json.
T383838autoconnect controls whether that hub is included in startup desired
connectivity. T383838auto_reconnect controls whether the service retries that hub
after disconnects/errors.
The health file at T383838healthcheck_path now includes both runtime
T383838connected_hubs and configured T383838configured_connected_hubs.
An optional T383838hub_hash config value is still accepted as a bootstrap fallback.
If present, it seeds T383838hubs_path on startup when no active hub has been saved
yet.
Example T383838hubs.json:
T282828
Tb4b4b4{
Tff7b72"active_hub"Tb4b4b4: Ta5d6ff"00112233445566778899aabbccddeeff"Tb4b4b4,
Tff7b72"hubs"Tb4b4b4: Tb4b4b4{
Tff7b72"00112233445566778899aabbccddeeff"Tb4b4b4: Tb4b4b4{
Tff7b72"autoconnect"Tb4b4b4: Tff7b72trueTb4b4b4,
Tff7b72"auto_reconnect"Tb4b4b4: Tff7b72trueTb4b4b4,
Tff7b72"connected"Tb4b4b4: Tff7b72trueTb4b4b4,
Tff7b72"policy"Tb4b4b4: Tb4b4b4{
Tff7b72"rooms"Tb4b4b4: Tb4b4b4[Ta5d6ff"general"Tb4b4b4]
Tb4b4b4}
Tb4b4b4},
Tff7b72"ffeeddccbbaa99887766554433221100"Tb4b4b4: Tb4b4b4{
Tff7b72"autoconnect"Tb4b4b4: Tff7b72falseTb4b4b4,
Tff7b72"auto_reconnect"Tb4b4b4: Tff7b72trueTb4b4b4,
Tff7b72"connected"Tb4b4b4: Tff7b72falseTb4b4b4,
Tff7b72"policy"Tb4b4b4: Tb4b4b4{
Tff7b72"rooms"Tb4b4b4: Tb4b4b4[Ta5d6ff"ops"Tb4b4b4]
Tb4b4b4}
Tb4b4b4}
Tb4b4b4}
Tb4b4b4}
T383838operator_identities and T383838admin_identities should include the bootstrap
identities for the person setting up the bot. They provide first-boot LXMF
administration before any role changes are persisted to T383838roles_path.
Operator/admin commands are enforced as LXMF-only control paths. If these
commands are sent in a room, the bot responds with an in-room notice that
includes the bot LXMF destination hash, and does not execute the command.
Manage Over LXMF
Management commands (all T383838operator and T383838admin commands) are intended for
LXMF control sessions.
Typical workflow:
1. Send a management command in-room once (for example, T383838!status).
2. Read the notice reply; it includes the bot LXMF destination hash.
3. Open an LXMF conversation to that destination.
4. Run management commands there (for example, T383838!status, T383838!hub list,
T383838!role list all, T383838!script list).
Notes:
• User commands remain available in rooms.
• If LXMF destination registration is temporarily unavailable, the bot returns
a notice that management commands are LXMF-only but cannot include a
destination hash.
• In-room LXMF-only notices are rate-limited by
T383838room_notice_cooldown_seconds.
For the canonical command list and roles, see T383838docs/COMMANDS.md.
The LXMF delivery display name is always derived from T383838nickname. Startup fails
fast if the LXMF destination cannot be registered with that display name.
The bot now emits structured JSON logs to stdout and a rotating file at
T383838log_path, writes runtime health status to T383838healthcheck_path, and tracks basic
alert metrics for reconnect churn, command denials, and LXMF send failures.
Run it:
T282828
rrc-bot
To use a different config file:
T282828
rrc-bot --config ./bot.json
Scripts
Full script authoring and live-load guide: T383838docs/SCRIPTING.md.
Commands
Canonical command catalog: T383838docs/COMMANDS.md.
Served by rngit 1.5.0 - Generated in 0.02s